home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / util / boot / buttonmenu_120.lha / buttonmenu / ButtonMenu.doc < prev    next >
Text File  |  1994-09-06  |  17KB  |  435 lines
  1.  
  2.                          BUTTONMENU V1.20 CONTENTS
  3.                          =========================
  4.  
  5.              Introduction
  6.              Disclaimer
  7.              Copyright
  8.              Distribution
  9.              Acknowledgements
  10.              Compatibility
  11.              Requirements
  12.              Getting Started
  13.              Reference
  14.                 How To Create a Button Menu
  15.                 How To Use a Button Menu
  16.                 Keyboard Shortcuts
  17.                 Height Confusion
  18.                 What to do if the items won't fit
  19.                 Limitations
  20.                 ButtonMenu Creator Menus
  21.                 ButtonMenu Creator Gadgets
  22.              Contacting the author
  23.              History
  24.  
  25.  
  26. INTRODUCTION
  27. ============
  28.    ButtonMenu allows Kickstart 2.0 (or higher) owners to create menus in
  29.    the form of a window full of GadTools buttons.  Two programs are
  30.    provided: one to allow you to create the menu and one which runs the
  31.    menu.  It is then possible to run your menu from a startup-sequence,
  32.    for example.  The GUI for the creator was designed to use Topaz 8,
  33.    but it will adapt to the current screen font if it is not too big.
  34.  
  35.    An added bonus is the ability to load ButtonMenu from within ButtonMenu
  36.    from within ButtonMenu and so on... This means you can nest menus to
  37.    create complicated menu systems.
  38.  
  39.  
  40. DISCLAIMER
  41. ==========
  42.    I cannot be held liable if this program causes you to lose valuable
  43.    data, nor can I be blamed if this program causes any other problems
  44.    with your system.  Any problems are entirely the user's responsibility.
  45.  
  46.  
  47. COPYRIGHT
  48. =========
  49.    ButtonMenu V1.20 - written with DICE C (2.07.56R) on an A600.
  50.    (c) Oliver Roberts, 1994
  51.  
  52.    ButtonMenu is public domain and the copyright remains with the author.
  53.  
  54.  
  55. DISTRIBUTION
  56. ============
  57.    ButtonMenu is freely distributable providing none of the distributed
  58.    files are changed in any way,  ButtonMenu is not sold for profit and
  59.    it is not included on any disks that are sold solely for profit.  If
  60.    ButtonMenu is to be sold for profit, permission must be obtained from
  61.    me, the author (Oliver Roberts).  Included in the above are magazine
  62.    coverdisks - let me know if you wish to use ButtonMenu menus on the
  63.    disk(s).
  64.  
  65.    For following files MUST be distributed together if the Creator is to
  66.    be included:
  67.  
  68.    ButtonMenu             (ButtonMenu Creator)
  69.    ButtonMenu.info
  70.    ButtonMenu.doc         (Document)
  71.    ButtonMenu.doc.info
  72.    ButtonMenu.guide       (Document in hypertext format)
  73.    ButtonMenu.guide.info
  74.    BMX                    (ButtonMenu Executor)
  75.    BMX.info
  76.    CHANGES                (Recent changes)
  77.    README                 (Additional Information)
  78.    reqtools.library       (KS2.0 V38 - Needed for Creator only)
  79.  
  80.    If you just want to distribute your created menu then you can
  81.    distribute the BMX program without the files above, if desired.
  82.  
  83.  
  84. ACKNOWLEDGEMENTS
  85. ================
  86.    Reqtools.library      (c) 1991-1994 Nico Francois
  87.  
  88.    The GUI for the Creator was mainly created with:
  89.    GadToolsBox V2.0b     (c) 1991-1993 Jaba Development
  90.  
  91.    Thanks to Rick Hughes for giving some ideas for new features, and for
  92.    the donation he made.
  93.  
  94.  
  95. COMPATIBILITY
  96. =============
  97.    ButtonMenu has been tested on an A600 with KS2.05 and KS3.0 using
  98.    NTSC/PAL, chip/fake fast, chip configurations.
  99.  
  100.    ButtonMenu is fully OS-Legal, it should work on ANY Amiga with
  101.    Kickstart 2.0 or higher!
  102.  
  103.  
  104. REQUIREMENTS
  105. ============
  106.    Any Amiga with Kickstart 2.0 (V36) or higher.  NTSC / PAL
  107.  
  108.    To run the Creator you will need these disk based libraries in the
  109.    LIBS: drawer on you boot disk or HD.
  110.  
  111.       diskfont.library (V36 or higher)
  112.       reqtools.library (V38 or higher)
  113.  
  114.    To run the Executor you do NOT need "reqtools.library" in the LIBS:
  115.    drawer, but if you are not using a ROM font (ie Topaz 8 or Topaz 9)
  116.    for the menu you will need "diskfont.library" if the font has not
  117.    already been loaded into RAM by another program.
  118.  
  119.  
  120. GETTING STARTED
  121. ===============
  122.    First make sure you have the libraries mentioned in the REQUIREMENTS
  123.    section installed in your LIBS: drawer on you HD or boot disk.
  124.  
  125.    From Workbench
  126.    --------------
  127.       Double-click on the ButtonMenu icon.
  128.  
  129.    From the Shell
  130.    --------------
  131.       Type `ButtonMenu' at the prompt.  There are no command line options
  132.       at present.
  133.  
  134.  
  135. How to Create a Button Menu
  136. ===========================
  137.    Making a menu is simple with ButtonMenu.  Just enter the items you wish
  138.    to be displayed to the user and the AmigaDOS command lines.  Keyboard
  139.    shortcuts can be assigned to each item as well (read the Keyboard
  140.    Shortcuts section for full details).
  141.  
  142.    Entering the commands is made simplier by providing a file requester:
  143.    just click on the gadget next to the command text gadget and select the
  144.    file you want to be run when the user clicks on the button.
  145.  
  146.    You can also ask for the command to be run in the background (uses the
  147.    AmigaDOS `run' command).
  148.  
  149.    Then select the font you wish to use for the buttons, the size of the
  150.    window and the title for the window.  Then select 'Save' from the menu.
  151.  
  152. How to Use a Button Menu
  153. ========================
  154.    Type `BMX <filename>' at a DOS prompt and the menu will appear.  Where
  155.    <filename> is the name of a ButtonMenu datafile which you have
  156.    previously saved (defaults to `BM.dat').  The menu should now appear.
  157.  
  158.    Alternatively, you may double click on a ButtonMenu datafile icon
  159.    and the menu will be displayed.
  160.  
  161.    Now just click on the button (or use a keyboard shortcut) to run the
  162.    corresponding commands, and click the close gadget when you have
  163.    finished.
  164.  
  165. Keyboard Shortcuts
  166. ==================
  167.    You can specify keyboard shortcuts for each item, if you want.  You
  168.    are not allowed to use the same key for more than one item (ButtonMenu
  169.    will tell you if you do).  Pressing any of the keys a..z in your
  170.    generated menu will have exactly the same effect as keys A..Z, thus
  171.    case is not important (unless you have the doc function enabled!)
  172.  
  173.    There are a few ways of denoting the keyboard shortcut in the item
  174.    text.  For example, with shortcut `B' you could have:
  175.  
  176.      [B]uttonMenu    or    (B)uttonMenu    or    {B}uttonMenu    etc...
  177.  
  178.    But the preferred way is to use an underscore character underneath
  179.    the letter to be emphasized - like most new Amiga applications.  You
  180.    do this in ButtonMenu by putting an `_' character directly before the
  181.    character to be underscored.  For example:
  182.  
  183.                  "_ButtonMenu"   produces     ButtonMenu
  184.                                               -
  185.  
  186.    Therefore, only use the underscore character for this purpose - using
  187.    more than one won't make any difference as the leftmost ones will be
  188.    ignored and not displayed.
  189.  
  190. Height Confusion
  191. ================
  192.    Some people may find the way the Height of the menu window is calculated
  193.    confusing - or uninteresting!  So for users who want to know why the
  194.    height is what it is, here is a little (well... long) explanation:
  195.  
  196.   "The Amiga OS will always use the screen's default font (set in Workbench
  197.    preferences) for the text in the title bars for each window opened.
  198.  
  199.    This means that the size of the title bar is variable when running the
  200.    menu with `BMX' and it is inconvenient to keep the height of the window
  201.    constant - the calculations in the ButtonMenu Creator would also have
  202.    to be used in the `BMX' program which would make the program nearly as
  203.    large as the creator, and would create incompatibilities with different
  204.    systems. I wanted the menu to be displayed as quickly as possible with
  205.    the smallest possible program.
  206.  
  207.    So, you are asked to enter the maximum inner height for the window,
  208.    which is the height of window excluding the title bar and bottom border.
  209.    The `Calculated Total Height' gadget will display an estimate for the
  210.    total height of the window, using the current screen font.
  211.  
  212.    Included is a `Height Adjust' feature.  This will alter the height
  213.    further, by removing any blank lines that will not be used giving a
  214.    slightly tidier menu.  To do this though, the `Calculated Total Height'
  215.    is calculated as before, but with the smallest possible height.     "
  216.  
  217. What to do if the items won't fit
  218. =================================
  219.    If you have the Adjust Height feature enabled, or are trying to save
  220.    your menu, and get any error message saying that the item(s) won't
  221.    fit in the window, then here are the possible causes/solutions:
  222.  
  223.    Causes
  224.    ------
  225.       * The text length of one of the items is too long
  226.         (and/or longer than the width of the window)
  227.       * The font is too large
  228.       * The window is too small
  229.       * Too many items
  230.  
  231.    Solutions (a bit obvious!)
  232.    ---------
  233.       * Shorten the length of the item texts
  234.       * Select a smaller font
  235.       * Enlarge the window
  236.       * Delete some of the longer items
  237.  
  238. Limitations
  239. ===========
  240.    The only limitation to the menus you create is that there must be at
  241.    least 1 item and no more than 100 items.  If you need more items -
  242.    let me know.
  243.  
  244. ButtonMenu Creator Menus
  245. ========================
  246.    Project
  247.    Help
  248.    Settings
  249.  
  250.    New    : Resets the creator by deleting all items.  Warning: Make
  251.             sure you have saved any wanted edits before selecting!
  252.  
  253.    Open   : Load a ButtonMenu datafile which you have previously saved.
  254.  
  255.    Save   : Save current edits back to the same file which you have
  256.             just loaded.  If this a new file, a file requester will be
  257.             available for you to enter a new name.
  258.  
  259.    Save As: Save current edits backs to another file.
  260.  
  261.    Test   : Display the menu which you have designed.  This uses the
  262.             external BMX program to load the menu - BMX must therefore
  263.             be in the search path somewhere.
  264.  
  265.    About  : Some copyright notes and version information.
  266.  
  267.    Quit   : Quit ButtonMenu unconditionally.
  268.  
  269.  
  270.    This menu provides some brief hints on how to use ButtonMenu, without
  271.    having to look at the document you are reading now.
  272.  
  273.  
  274.    Save Icons?  : If you select this item, icons will be saved with your
  275.                   datafiles so that the menus can be started from
  276.                   Workbench with a click of a button.
  277.  
  278.    Save Settings: Save the current state of the Save Icons flag in the
  279.                   "s:ButtonMenu.config" file.
  280.  
  281. ButtonMenu Creator Gadgets
  282. ==========================
  283.    Item Gadgets - Main
  284.                   Secondary Function (optional)
  285.    General Gadgets
  286.  
  287.  
  288.    New Item   : Add a new item to the menu, after the currently selected
  289.                 one (or the start if there are no items).
  290.  
  291.    Delete Item: Erase the currently selected menu item.
  292.  
  293.    Up         : Move the currently selected item up the list.
  294.  
  295.    Down       : Move the currently selected item down the list.
  296.  
  297.    Item Text  : The text to be displayed on one of the menu buttons.  If
  298.                 you put a `_' character in front of another character,
  299.                 ButtonMenu will denote that letter as the keyboard
  300.                 shortcut (you must also but this letter in the keyboard
  301.                 shortcut requester).
  302.  
  303.    DOS        : The command to be executed when the corresponding menu
  304.     Command     button is clicked.  This is to be in the same format as
  305.                 you would run it from the CLI manually.  You can also
  306.                 select commands via a file requester, so you don't need
  307.                 to remember the exact filenames.
  308.  
  309.    Keyboard   : Specifies an optional key that performs the same function
  310.     Shortcut    as clicking on the button on the finished menu.
  311.  
  312.    Run command: Tells the Amiga to run that command as a background task.
  313.     in          This does the same thing as `run >NIL: <command>' would
  314.     background  do, where <command> is the contents of the DOS Command
  315.                 gadget.  This command is activated by the left mouse
  316.                 button or the keyboard shortcut on the final menu.
  317.  
  318.  
  319.    Enable Doc : Tell ButtonMenu that you want this item to have a second
  320.     Function    function which will be activated by holding the right
  321.                 mouse button or shift key and then pressing the left mouse
  322.                 button or keyboard shortcut.
  323.  
  324.    Doc        : In conjuntion with the Doc Reader gadget you may enter the
  325.     Filename    filename of the corresponding document.  The filename will
  326.                 be loaded by the Doc Reader.  However, you may specify no
  327.                 doc reader and enter an AmigaDOS commandline in this
  328.                 gadget - this provides maximum flexibility.
  329.  
  330.  
  331.     Font Used : The font to be used for the item text on the menu buttons.
  332.     For Items   Click the Choose Font button to change the font.
  333.  
  334.     Title     : Text to be displayed in the title bar of your menu - uses
  335.                 a separate font.
  336.  
  337.     Width     : Width of the menu window (in pixels).
  338.  
  339.     Inner     : The height of your window excluding the title bar and
  340.     Height      bottom border.
  341.  
  342.     Adjust    : With this feature turned on, any blank lines at the bottom
  343.     Height      of your menu window will be removed by decreasing the
  344.                 height.  Checks will also be made to see if your items
  345.                 will actually fit in the menu window with the dimension
  346.                 you have specified whenever you alter these, the font or
  347.                 the Item Text.  With the feature off, these checks are
  348.                 only made when saving.
  349.  
  350.     Calculated: This is the estimated total height of your window including
  351.     Total       the borders.  Assumes the screen font you will use for the
  352.     Height      menu will be the same as the current one - that is why it
  353.                 is an estimate.
  354.  
  355.     Centre    : Makes the menu appear in the centre of your screen.
  356.      Window
  357.  
  358.     Single    : Allows only ONE choice to be made on the menu.  After the
  359.      Choice     corresponding command has returned, the menu will close.
  360.  
  361.     Doc       : This is an optional field which may be filled with the
  362.      Reader     intended command line of your preferred document reader
  363.                 (e.g "run c:ppmore").  This field will be used by the
  364.                 secondary functions of all items, if it is not empty.
  365.  
  366.  
  367. CONTACTING THE AUTHOR
  368. =====================
  369.    You can contact me via e-mail at this address:
  370.  
  371.       robeoy@essex.ac.uk
  372.  
  373.    Or via snail-mail, my permanent home address is:
  374.  
  375.       30 Tillett Road
  376.       Norwich
  377.       Norfolk
  378.       NR3 4BJ
  379.       ENGLAND
  380.  
  381.  
  382. HISTORY
  383. =======
  384.  
  385. V1.20 - August 31 1994
  386.  
  387. ButtonMenu nows uses functions available in KS 2.0 (or higher) instead of
  388. the equivalent ANSI C functions.  The has resulted in a drastic decrease in
  389. executable size for the BMX executor (about a 50% reduction).
  390.  
  391. Added a "Test" option to the project menu in the creator which uses BMX
  392. to run the menu.
  393.  
  394. Added Workbench support to BMX which allows ButtonMenus to be loaded via
  395. an icon.  It then made sense to add a settings menu with a Save Icons
  396. option and a configuration file saved in s: .
  397.  
  398. Changed the Adjust Height error handling slightly resulting in less
  399. annoying requesters (also corrected a spelling mistake in the error
  400. message).
  401.  
  402. Added a zoom gadget to the menu windows that are created.
  403.  
  404. Added an option to centre the ButtonMenu when it is opened.
  405.  
  406. New option to allow ButtonMenus to act more like requesters (ie only one
  407. choice is allowed - then the window is closed automatically).
  408.  
  409. Amigaguide documentation provided in addition to the standard text doc.
  410.  
  411. Bug Fix: Removed a bug which caused gadgets in the window to be
  412.          refreshed more than once - resulting in flickering.
  413. ===========================================================================
  414. V1.10 - August 15 1994 (BETA version - not publically released)
  415.  
  416. Added a keyboard shortcut facility - datafiles changed accordingly, but
  417. old ones are still supported.
  418.  
  419. Added an option to display docs as a secondary action.
  420.  
  421. New-look menus when ButtonMenu is run on KS 3.0 or higher.
  422.  
  423. Bug fixes: I discovered a bug concerning the 4 buttons underneath the
  424.            item listview gadget.  Now, the buttons are checked in addition
  425.            to being disabled when appropriate.
  426.  
  427.            A possible bug in the Executor message handler - fixed.
  428.  
  429.            Not all the text strings were freed properly which sometimes
  430.            gave memory failures (ie Memory Insane) - fixed this.
  431. ===========================================================================
  432. V1.00 - July 28 1994
  433.  
  434. First release.
  435.